Skip to main content

signercli -privkey

Private Key Management Command – Full Reference​

1. Overview​

The signercli -privkey command provides private key lifecycle management on the Signer Server.

It allows users to:

  • List private keys
  • Inspect private key metadata
  • Upload private keys
  • Delete private keys
  • Link private keys to certificates
  • Unlink private keys from certificates

Important

Private keys are managed independently from certificates.

A certificate becomes usable for signing only after a private key is linked to it.

2. Command Usage​

signercli -privkey <command> [options]

3. Commands​

CommandDescription
listList all private keys
get <id>Get private key details
upload <file>Upload a private key
delete <id>Delete a private key
link <key-id> <cert-id>Link private key to a certificate
unlink <key-id>Unlink private key from a certificate
helpDisplay help message

4. Authentication and Global Options​

Required Authentication​

OptionDescription
-api-key <key>API key authentication (required)
-host <url>Signer Server URL (default: https://localhost:7443)

signercli -privkey always requires an API key.

Login-based authentication is not supported for private key management.

Output Format​

OptionDescription
-format <type>Output format: text, json

5. Listing Private Keys​

List All Private Keys​

signercli -privkey list -api-key cdk_xxx

JSON Output (Automation)​

signercli -privkey list -api-key cdk_xxx -format json

Useful for:

  • CI/CD pipelines
  • Auditing
  • Automated key-to-certificate mapping

6. Viewing Private Key Details​

signercli -privkey get <key_id> -api-key cdk_xxx

Displays metadata such as:

  • Key ID
  • Key name
  • Storage backend (DB / SW_HSM / HW_HSM)
  • Linked certificate ID (if any)
  • Creation timestamp

The private key material is never displayed or exported.

7. Uploading Private Keys​

Command Syntax​

signercli -privkey upload <file> [options]

Upload Options​

OptionDescription
-name <name>Human-readable key name
-password <pwd>Password for encrypted private key
-hsm-pin <pin>HSM PIN (required for HSM-stored keys)

Upload Examples​

Upload an Unencrypted Private Key​

signercli -privkey upload server.key -api-key cdk_xxx

Upload with a Key Name​

signercli -privkey upload server.key \
  -name "Web Server Key" \
  -api-key cdk_xxx

Upload an Encrypted Private Key​

signercli -privkey upload encrypted.key \
  -password secret \
  -api-key cdk_xxx

Upload Notes​

  • Supported key formats depend on server policy
  • Uploaded private keys are stored securely
  • Private keys cannot be downloaded after upload

8. Linking Private Keys to Certificates​

signercli -privkey link <key_id> <cert_id> -api-key cdk_xxx

Effects:

  • Associates the private key with the certificate
  • Enables signing operations using that certificate
  • A certificate can have only one active private key

Typical Workflow​

signercli -cert upload cert.pem -api-key cdk_xxx
signercli -privkey upload key.pem -api-key cdk_xxx
signercli -privkey link key123 cert456 -api-key cdk_xxx

9. Unlinking Private Keys​

signercli -privkey unlink <key_id> -api-key cdk_xxx

Behavior:

  • Removes the association between the key and certificate
  • The private key remains stored
  • The certificate becomes unusable for signing until re-linked

10. Deleting Private Keys​

Delete a Private Key​

signercli -privkey delete <key_id> -api-key cdk_xxx

Delete an HSM-Stored Private Key​

signercli -privkey delete <key_id> \
  -hsm-pin 1234 \
  -api-key cdk_xxx

⚠️ Deletion is irreversible.

Deleting a private key permanently disables any certificate linked to it.

11. HSM Considerations​

  • HSM-backed keys require hsm-pin for sensitive operations
  • PINs are used transiently and are not stored
  • HSM policies may restrict deletion or linking operations

12. Relationship to Other Commands​

CommandDescription
signercli -certCertificate management
signercli -cert-apiFull certificate lifecycle via API
signercli -pubkeyPublic key management
signercli -csrCSR generation

13. Typical Use Cases​

  • Secure CI/CD signing pipelines
  • HSM-backed production signing
  • Centralized private key management
  • Certificate-to-key lifecycle control

14. Summary​

The signercli -privkey command provides secure, API-driven private key management, enabling:

  • Strict separation between keys and certificates
  • Controlled linking and unlinking
  • HSM-aware operations
  • Automation-friendly workflows

It is a critical component of enterprise-grade signing infrastructure.